home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 4 / Meeting Pearls Vol. IV (1996)(GTI - Schatztruhe)[!].iso / Pearls / libs / bgui / Docs / methods.doc < prev    next >
Text File  |  1995-04-23  |  7KB  |  189 lines
  1.  
  2.                File: methods.doc
  3.         Description: Extra methods documentation.
  4.           Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.                      (C) Copyright 1994-1995 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. methods/--background--
  13. groupclass/GRM_DIMENSIONS
  14. windowclass/WM_KEYACTIVE
  15. windowclass/WM_KEYINPUT
  16. windowclass/WM_KEYINACTIVE
  17.  
  18. methods/--background--
  19.  
  20.     DESCRIPTION
  21.         Gadget  classes  that  want to work in a BGUI environment will need to
  22.         know about a set of extra methods on top of the  normal system  gadget
  23.         class methods. This document describes these methods.
  24.  
  25.         Not    all    system    gadgetclass    methods    will    reach   your
  26.         class.  The following   standard   system   gadgetclass   methods  are
  27.         passed onto your class:
  28.  
  29.                 GM_HITTEST
  30.                 GM_RENDER
  31.                 GM_GOACTIVE
  32.                 GM_HANDLEINPUT
  33.                 GM_GOINACTIVE
  34.  
  35.         The  following  methods  are  not used in a BGUI context and therefore
  36.         will not be send to your class:
  37.  
  38.                 GM_HELPTEST
  39.                 GM_LAYOUT
  40.  
  41. groupclass/GRM_DIMENSIONS                            groupclass/GRM_DIMENSIONS
  42.  
  43.     NAME
  44.         GRM_DIMENSIONS
  45.  
  46.     FUNCTION
  47.         To inquire about a gadget object it's minimum  width and  height.  The
  48.         group class sends out this method  to all  it's  members to  ensure  a
  49.         correct  layout.   This  method  uses  the  following  custom  message
  50.         structure:
  51.  
  52.         struct grmDimensions {
  53.                 ULONG                   MethodID;       /* GRM_DIMENSIONS */
  54.                 struct GadgetInfo      *grmd_GInfo;
  55.                 struct RastPort        *grmd_RPort;
  56.                 struct {
  57.                         UWORD          *Width;
  58.                         UWORD          *Height;
  59.                 }                       grmd_MinSize;
  60.                 ULONG                   grmd_Flags;
  61.         };
  62.  
  63.         grmd_GInfo -- This  field  will  always  read  NULL!  It will probably
  64.                 become obsolete in one of the next versions.   Please  do  not
  65.                 make any assumptions about it's contents.   Simply  ignore  it
  66.                 until further notice.
  67.  
  68.         grmd_RPort -- This points to a RastPort which can be  used  to perform
  69.                 text width/height computations etc. in.   Do  *not*  render in
  70.                 this RastPort.
  71.  
  72.         grmd_MinSize --  This  field  contains  two pointers in which you must
  73.                 store the results of your computations.   Note  that you  must
  74.                 *add* your results to the results you got from the superclass.
  75.  
  76.                 Example:
  77.  
  78.                 switch ( msg->MethodID ) {
  79.                     case    GRM_DIMENSIONS:
  80.                         /*
  81.                         **      First the superclass...
  82.                         **/
  83.                         DoSuperMethodA( class, object, msg );
  84.                         /*
  85.                         **      Compute your minimum sizes.
  86.                         **/
  87.                         ...
  88.                         /*
  89.                         **      Add results.
  90.                         **/
  91.                         *( msg->grmd_MinSize.Width  ) += your_min_width;
  92.                         *( msg->grmd_MinSize.Height ) += your_min_height;
  93.                         break;
  94.                 }
  95.  
  96.                 There  might  be  cases  in  which  you  want  to  overide the
  97.                 superclass  results  which  is  perfectly  legal to do but you
  98.                 should be aware that wrong values here might  seriously  screw
  99.                 up the look of the resulting GUI.
  100.  
  101.         grmd_Flags -- This field may contain any of the following flags:
  102.  
  103.                 GDIMF_NO_FRAME -- This will tell the baseclass not to take the
  104.                         attached frame into consideration  when  computing the
  105.                         minimum size.
  106.  
  107. windowclass/WM_KEYACTIVE                              windowclass/WM_KEYACTIVE
  108.  
  109.     NAME
  110.         WM_KEYACTIVE
  111.  
  112.     FUNCTION
  113.         To  tell  the  object  that  it  is  activated  by  a key-press. Uppon
  114.         receiving  this message you can setup any additional resources you may
  115.         need  to  go  active.  This  method  uses the following custom message
  116.         structure:
  117.  
  118.         struct wmKeyInput {
  119.                 ULONG                    MethodID; /* WM_KEY_ACTIVE */
  120.                 struct GadgetInfo       *wmki_GInfo;
  121.                 struct InputEvent       *wmki_IEvent;
  122.                 ULONG                   *wmki_ID;
  123.                 STRPTR                   wmki_Key;
  124.         };
  125.  
  126.         wmki_GInfo -- This points to a GadgetInfo structure.
  127.  
  128.         wmki_IEvent -- A pointer to a InputEvent structure  which is the event
  129.                 that  triggered  the  activation.   The  event class is always
  130.                 IECLASS_RAWKEY. This event can be used to check for  qualifier
  131.                 keys etc.
  132.  
  133.         wmki_ID -- In  this field you can store the ID of the  object when the
  134.                 activation has resulted in a change that needs to be notified.
  135.                 The value put  in  here is  returned  by the  windowclass it's
  136.                 WM_HANDLEIDCMP method.
  137.  
  138.         wmki_Key -- This points to the key string which  has been  assigned to
  139.                 the object with the windowclass it's WM_GADGETKEY method.
  140.  
  141.         This method should return any of the following return codes:
  142.  
  143.         WMKF_MEACTIVE -- The object can go/remains active.
  144.         WMKF_CANCEL -- The keyboard activation is cancelled.
  145.         WMKF_VERIFY -- The keyboard activation is complete and the  ID  set in
  146.                 the wmki_ID field is notified.
  147.         WMKF_ACTIVATE -- Returning this tell's the windowclass to activate the
  148.                 gadget using the intuition.library it's ActivateGadget() call.
  149.  
  150.     SEE ALSO
  151.         windowclass/WM_KEYINPUT, windowclass/WM_KEYINACTIVE,
  152.         windowclass/WM_KEYINACTIVE windowclass/WM_HANDLEIDCMP,
  153.         windowclass/WM_GADGETKEY, intuition.library/ActivateGadget()
  154.  
  155. windowclass/WM_KEYINPUT                                windowclass/WM_KEYINPUT
  156.  
  157.     NAME
  158.         WM_KEYINPUT
  159.  
  160.     FUNCTION
  161.         This method is send to the object  continually  when the  WM_KEYACTIVE
  162.         returned WMKF_MEACTIVE  and the  object has  gone active.  This method
  163.         uses the same custom message structure as the WM_KEYACTIVE method does
  164.         and it should return any of the same return codes as described  in the
  165.         WM_KEYACTIVE method with the exception of WMKF_ACTIVATE.
  166.  
  167.         A good example of this method  is  the  buttonclass  which  uses  this
  168.         method  to  scan  for  the SHIFT  qualifier and/or the ESC  key  which
  169.         both cancel a keyboard button selection.
  170.  
  171.     SEE ALSO
  172.         windowclass/WM_KEYACTIVE
  173.  
  174. windowclass/WM_KEYINACTIVE                          windowclass/WM_KEYINACTIVE
  175.  
  176.     NAME
  177.         WM_KEYINACTIVE
  178.  
  179.     FUNCTION
  180.         When the key-activation of an object is done or aborted by some  other
  181.         event this method is called to tell to object  to go  inactive.   This
  182.         gives you the oppertunity to release the resources that you might have
  183.         obtained with the WM_KEYACTIVE method.
  184.  
  185.         No return code defined.
  186.  
  187.     SEE ALSO
  188.         windowclass/WM_KEYACTIVE
  189.